/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
/* vim:set et sts=4: */
/* IBust - IBus with Traditional interface
 * Copyright(c) 2013 Daniel Sun
 * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
 * Copyright (C) 2008-2010 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#if !defined (__IBUST_H_INSIDE__) && !defined (IBUST_COMPILATION)
#error "Only <ibust.h> can be included directly"
#endif

/**
 * SECTION: ibustbus
 * @short_description: Connect with IBust daemon.
 * @stability: Stable
 *
 * An IBustBus connects with IBust daemon.
 */
#ifndef __IBUST_BUS_H_
#define __IBUST_BUS_H_

#include <gio/gio.h>
#include "ibustinputcontext.h"
#include "ibustconfig.h"
#include "ibustcomponent.h"

/*
 * Type macros.
 */

/* define GOBJECT macros */
#define IBUST_TYPE_BUS             \
    (ibust_bus_get_type ())
#define IBUST_BUS(obj)             \
    (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUST_TYPE_BUS, IBustBus))
#define IBUST_BUS_CLASS(klass)     \
    (G_TYPE_CHECK_CLASS_CAST ((klass), IBUST_TYPE_BUS, IBustBusClass))
#define IBUST_IS_BUS(obj)          \
    (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUST_TYPE_BUS))
#define IBUST_IS_BUS_CLASS(klass)  \
    (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUST_TYPE_BUS))
#define IBUST_BUS_GET_CLASS(obj)   \
    (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUST_TYPE_BUS, IBustBusClass))

G_BEGIN_DECLS

typedef struct _IBustBus IBustBus;
typedef struct _IBustBusClass IBustBusClass;
typedef struct _IBustBusPrivate IBustBusPrivate;

/**
 * IBustBus:
 *
 * An opaque data type representing IBust bus (daemon communication) status.
 */
struct _IBustBus {
    IBustObject parent;
    /* instance members */

    IBustBusPrivate *priv;
};

struct _IBustBusClass {
    IBustObjectClass parent;
    /* class members */
};

GType        ibust_bus_get_type          (void);

/**
 * ibust_bus_new:
 * @returns: A newly allocated #IBustBus instance, and the instance is not floating.
 *
 * New an #IBustBus instance.
 */
IBustBus     *ibust_bus_new               (void);

/**
 * ibust_bus_new_async:
 * @returns: A newly allocated #IBustBus instance, and the instance is not floating.
 *
 * New an #IBustBus instance. The instance will asynchronously connect to the IBust
 * daemon.
 */
IBustBus     *ibust_bus_new_async         (void);


/**
 * ibust_bus_is_connected:
 * @bus: An #IBustBus.
 * @returns: %TRUE if @bus is connected, %FALSE otherwise.
 *
 * Return %TRUE if @bus is connected to IBust daemon.
 */
gboolean     ibust_bus_is_connected      (IBustBus        *bus);

/**
 * ibust_bus_get_connection:
 * @bus: An #IBustBus.
 * @returns: (transfer none): A #GDBusConnection of an #IBustBus instance.
 *
 * Return #GDBusConnection of an #IBustBus instance.
 */
GDBusConnection *
             ibust_bus_get_connection    (IBustBus        *bus);

/**
 * ibust_bus_hello:
 * @bus: An #IBustBus.
 * @returns: The unique name of IBust process in DBus.
 *
 * This function sends a "HELLO" message to DBus daemon,
 * which replies the unique name of current IBust process.
 */
const gchar *ibust_bus_hello             (IBustBus        *bus);

/**
 * ibust_bus_request_name:
 * @bus: the IBustBus instance to be processed.
 * @name: Name to be requested.
 * @flags: IBustBusNameFlag.
 * @returns: 0 if failed; IBustBusRequestNameReply otherwise.
 *
 * Request a name from IBust daemon synchronously.
 */
guint32      ibust_bus_request_name      (IBustBus        *bus,
                                         const gchar    *name,
                                         guint32         flags);

/**
 * ibust_bus_request_name_async:
 * @bus: An #IBustBus.
 * @name: Name to be requested.
 * @flags: Flags (FixMe).
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL
 *      if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Request a name from IBust daemon asynchronously.
 */
void        ibust_bus_request_name_async (IBustBus        *bus,
                                         const gchar    *name,
                                         guint           flags,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_request_name_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_request_name_async().
 * @error: Return location for error or %NULL.
 * @returns: 0 if failed; positive number otherwise.
 *
 * Finishes an operation started with ibust_bus_request_name_async().
 */
guint       ibust_bus_request_name_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_release_name:
 * @bus: An #IBustBus.
 * @name: Name to be released.
 * @returns: 0 if failed; positive number otherwise.
 *
 * Release a name to IBust daemon synchronously.
 */
guint        ibust_bus_release_name      (IBustBus        *bus,
                                         const gchar    *name);

/**
 * ibust_bus_release_name_async:
 * @bus: An #IBustBus.
 * @name: Name to be released.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Release a name to IBust daemon asynchronously.
 */
void         ibust_bus_release_name_async
                                        (IBustBus        *bus,
                                         const gchar    *name,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_release_name_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_release_name_async().
 * @error: Return location for error or %NULL.
 * @returns: 0 if failed; positive number otherwise.
 *
 * Finishes an operation started with ibust_bus_release_name_async().
 */
guint        ibust_bus_release_name_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_list_queued_owners:
 * @bus: An IBustBus.
 * @name: Name to be queried.
 * @returns: (transfer full) (element-type utf8):
 *           The unique bus names of connections currently queued for @name.
 *
 * Lists the unique bus names of connections currently queued for a bus name.
 *
 * FIXME add an asynchronous version.
 */
GList *      ibust_bus_list_queued_owners
                                        (IBustBus      *bus,
                                         const gchar  *name);

/**
 * ibust_bus_name_has_owner:
 * @bus: An #IBustBus.
 * @name: Name to be checked.
 * @returns: %TRUE if the name has owner, %FALSE otherwise.
 *
 * Checks whether the name has owner synchronously.
 */
gboolean     ibust_bus_name_has_owner    (IBustBus        *bus,
                                         const gchar    *name);

/**
 * ibust_bus_name_has_owner_async:
 * @bus: An #IBustBus.
 * @name: Name to be checked.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Checks whether the name has owner asynchronously.
 */
void         ibust_bus_name_has_owner_async
                                        (IBustBus        *bus,
                                         const gchar    *name,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_name_has_owner_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_name_has_owner_async().
 * @error: Return location for error or %NULL.
 * @returns: %TRUE if the name has owner, %FALSE otherwise.
 *
 * Finishes an operation started with ibust_bus_name_has_owner_async().
 */
gboolean     ibust_bus_name_has_owner_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_list_names:
 * @bus: An #IBustBus.
 * @returns: (transfer full) (element-type utf8): Lists that attached to @bus.
 *
 * Return lists that attached to @bus.
 * <note><para>[FixMe] Not implemented yet, only return NULL.</para></note>
 * <note><para>[FixMe] Add async version.</para></note>
 */
GList       *ibust_bus_list_names        (IBustBus        *bus);

/**
 * ibust_bus_add_match:
 * @bus: An #IBustBus.
 * @rule: Match rule.
 * @returns: %TRUE if the rule is added. %FALSE otherwise.
 *
 * Add a match rule to an #IBustBus synchronously.
 */
gboolean     ibust_bus_add_match         (IBustBus        *bus,
                                         const gchar    *rule);

/**
 * ibust_bus_add_match_async:
 * @bus: An #IBustBus.
 * @rule: Match rule.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Add a match rule to an #IBustBus asynchronously.
 */
void         ibust_bus_add_match_async   (IBustBus        *bus,
                                         const gchar    *rule,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_add_match_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_add_match_async().
 * @error: Return location for error or %NULL.
 * @returns: %TRUE if the rule is added. %FALSE otherwise.
 *
 * Finishes an operation started with ibust_bus_add_match_async().
 */
gboolean     ibust_bus_add_match_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_remove_match:
 * @bus: An #IBustBus.
 * @rule: Match rule.
 * @returns: %TRUE if the rule is removed. %FALSE otherwise.
 *
 * Remove a match rule to an #IBustBus synchronously.
 */
gboolean     ibust_bus_remove_match      (IBustBus        *bus,
                                         const gchar    *rule);

/**
 * ibust_bus_remove_match_async:
 * @bus: An #IBustBus.
 * @rule: Match rule.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Remove a match rule to an IBustBus asynchronously.
 */
void         ibust_bus_remove_match_async
                                        (IBustBus        *bus,
                                         const gchar    *rule,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_remove_match_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_remove_match_async().
 * @error: Return location for error or %NULL.
 * @returns: %TRUE if the rule is removed. %FALSE otherwise.
 *
 * Finishes an operation started with ibust_bus_remove_match_async().
 */
gboolean     ibust_bus_remove_match_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_get_name_owner:
 * @bus: An #IBustBus.
 * @name: Name.
 * @returns: Owner of the name. The returned value must be freed with g_free().
 *
 * Return the name owner synchronously.
 */
gchar       *ibust_bus_get_name_owner    (IBustBus        *bus,
                                         const gchar    *name);

/**
 * ibust_bus_get_name_owner_async:
 * @bus: An #IBustBus.
 * @name: Name.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Return the name owner asynchronously.
 */
void         ibust_bus_get_name_owner_async
                                        (IBustBus        *bus,
                                         const gchar    *name,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_get_name_owner_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_get_name_owner_async().
 * @error: Return location for error or %NULL.
 * @returns: Owner of the name. The returned value must be freed with g_free().
 *
 * Finishes an operation started with ibust_bus_get_name_owner_async().
 */
gchar       *ibust_bus_get_name_owner_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);
/* declare ibust methods */

/**
 * ibust_bus_exit:
 * @bus: An #IBustBus.
 * @restart: Whether restarting the ibust.
 * @returns: %TRUE if the "Exit" call is suceeded, %FALSE otherwise.
 *
 * Exit or restart ibust-daemon synchronously.
 */
gboolean     ibust_bus_exit              (IBustBus        *bus,
                                         gboolean        restart);

/**
 * ibust_bus_exit_async:
 * @bus: An #IBustBus.
 * @restart: Whether restarting the ibust.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Exit or restart ibust-daemon asynchronously.
 */
void        ibust_bus_exit_async         (IBustBus        *bus,
                                         gboolean        restart,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_exit_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_exit_async().
 * @error: Return location for error or %NULL.
 * @returns: %TRUE if the "Exit" call is suceeded, %FALSE otherwise.
 *
 * Finishes an operation started with ibust_bus_exit_async().
 */
gboolean    ibust_bus_exit_async_finish  (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_create_input_context:
 * @bus: An #IBustBus.
 * @client_name: Name of client.
 * @returns: An newly allocated #IBustInputContext if the "CreateInputContext"
 *      call is suceeded, %NULL otherwise.
 *
 * Create an input context for client synchronously.
 */
IBustInputContext *
            ibust_bus_create_input_context
                                        (IBustBus        *bus,
                                         const gchar    *client_name);

/**
 * ibust_bus_create_input_context_async:
 * @bus: An #IBustBus.
 * @client_name: Name of client.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
 *      It should not be %NULL.
 * @user_data: The data to pass to callback.
 *
 * Create an input context for client asynchronously.
 */
void        ibust_bus_create_input_context_async
                                        (IBustBus        *bus,
                                         const gchar    *client_name,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_create_input_context_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_create_input_context_async().
 * @error: Return location for error or %NULL.
 * @returns: An newly allocated #IBustInputContext if the "CreateInputContext"
 *      call is suceeded, %NULL otherwise.
 *
 * Finishes an operation started with ibust_bus_create_input_context_async().
 */
IBustInputContext *
             ibust_bus_create_input_context_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_current_input_context:
 * @bus: An #IBustBus.
 * @returns: The named of currently focued #IBustInputContext if the
 *            "CurrentInputContext" call suceeded, %NULL otherwise. The return
 *            value must be freed with g_free().
 *
 * Get the current focused input context synchronously.
 */
gchar       *ibust_bus_current_input_context
                                        (IBustBus        *bus);

/**
 * ibust_bus_current_input_context_async:
 * @bus: An #IBustBus.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Get the current focused input context asynchronously.
 */
void         ibust_bus_current_input_context_async
                                        (IBustBus        *bus,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_current_input_context_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_current_input_context_async().
 * @error: Return location for error or %NULL.
 * @returns: The named of currently focued IBustInputContext if the
 *            "CurrentInputContext" call suceeded, %NULL otherwise. The return
 *            value must be freed with g_free().
 *
 * Finishes an operation started with ibust_bus_current_input_context_async().
 */
gchar       *ibust_bus_current_input_context_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_register_component:
 * @bus: An #IBustBus.
 * @component: A input engine component.
 * @returns: %TRUE if the "RegisterComponent" call is suceeded, %FALSE otherwise.
 *
 * Register a componet to an #IBustBus synchronously.
 */
gboolean     ibust_bus_register_component
                                        (IBustBus        *bus,
                                         IBustComponent  *component);

/**
 * ibust_bus_register_component_async:
 * @bus: An #IBustBus.
 * @component: A input engine component.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Register a componet to an #IBustBus asynchronously.
 */
void         ibust_bus_register_component_async
                                        (IBustBus        *bus,
                                         IBustComponent  *component,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer            user_data);

/**
 * ibust_bus_register_component_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_register_component_async().
 * @error: Return location for error or %NULL.
 * @returns: %TRUE if the "RegisterComponent" call is suceeded, %FALSE otherwise.
 *
 * Finishes an operation started with ibust_bus_register_component_async().
 */
gboolean     ibust_bus_register_component_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_list_engines:
 * @bus: An #IBustBus.
 * @returns: (transfer container) (element-type IBustEngineDesc): A List of engines.
 *
 * List engines synchronously.
 */
GList       *ibust_bus_list_engines      (IBustBus        *bus);

/**
 * ibust_bus_list_engines_async:
 * @bus: An #IBustBus.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL
 *      if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * List engines asynchronously.
 */
void         ibust_bus_list_engines_async
                                        (IBustBus        *bus,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_list_engines_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_list_engines_async().
 * @error: Return location for error or %NULL.
 * @returns: (transfer container) (element-type IBustEngineDesc): A List of engines.
 *
 * Finishes an operation started with ibust_bus_list_engines_async().
 */
GList       *ibust_bus_list_engines_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_list_active_engines:
 * @bus: An #IBustBus.
 * @returns: (transfer container) (element-type IBustEngineDesc): A List of active engines.
 *
 * List active engines synchronously.
 */
GList       *ibust_bus_list_active_engines
                                        (IBustBus        *bus);

/**
 * ibust_bus_list_active_engines_async:
 * @bus: An #IBustBus.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL
 *      if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * List active engines asynchronously.
 */
void         ibust_bus_list_active_engines_async
                                        (IBustBus        *bus,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_list_active_engines_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_list_active_engines_async().
 * @error: Return location for error or %NULL.
 * @returns: (transfer container) (element-type IBustEngineDesc): A List of active engines.
 *
 * Finishes an operation started with ibust_bus_list_active_engines_async().
 */
GList       *ibust_bus_list_active_engines_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError         **error);

/**
 * ibust_bus_get_engines_by_names:
 * @bus: An #IBustBus.
 * @names: (array zero-terminated=1): A %NULL-terminated array of names.
 * @returns: (array zero-terminated=1) (transfer full): A %NULL-terminated array of engines.
 *
 * Get engines by given names synchronously. If some engine names do not exist, this function
 * will simplly ignore them, and return rest of engines.
 * TODO(penghuang): add asynchronous version
 */
IBustEngineDesc **
             ibust_bus_get_engines_by_names
                                        (IBustBus             *bus,
                                         const gchar * const *names);
/**
 * ibust_bus_get_use_sys_layout:
 * @bus: An #IBustBus.
 * @returns: %TRUE if "use_sys_layout" option is enabled.
 *
 * Check if the bus's "use_sys_layout" option is enabled or not synchronously.
 */
gboolean     ibust_bus_get_use_sys_layout
                                        (IBustBus        *bus);

/**
 * ibust_bus_get_use_sys_layout_async:
 * @bus: An #IBustBus.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Check if the bus's "use_sys_layout" option is enabled or not asynchronously.
 */
void         ibust_bus_get_use_sys_layout_async
                                        (IBustBus        *bus,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_get_use_sys_layout_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_get_use_sys_layout_async().
 * @error: Return location for error or %NULL.
 * @returns: TRUE if "use_sys_layout" option is enabled.
 *
 * Finishes an operation started with ibust_bus_get_use_sys_layout_async().
 */
gboolean     ibust_bus_get_use_sys_layout_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_get_use_global_engine:
 * @bus: An #IBustBus.
 * @returns: TRUE if "use_global_engine" option is enabled.
 *
 * Check if the bus's "use_global_engine" option is enabled or not synchronously.
 */
gboolean     ibust_bus_get_use_global_engine
                                        (IBustBus        *bus);

/**
 * ibust_bus_get_use_global_engine_async:
 * @bus: An #IBustBus.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Check if the bus's "use_global_engine" option is enabled or not asynchronously.
 */
void         ibust_bus_get_use_global_engine_async
                                        (IBustBus        *bus,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_get_use_global_engine_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_get_use_global_engine_async().
 * @error: Return location for error or %NULL.
 * @returns: %TRUE if "use_global_engine" option is enabled.
 *
 * Finishes an operation started with ibust_bus_get_use_global_engine_async().
 */
gboolean     ibust_bus_get_use_global_engine_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError         **error);

/**
 * ibust_bus_is_global_engine_enabled:
 * @bus: An #IBustBus.
 * @returns: %TRUE if the current global engine is enabled.
 *
 * Check if the current global engine is enabled or not synchronously.
 */
gboolean     ibust_bus_is_global_engine_enabled
                                        (IBustBus        *bus);

/**
 * ibust_bus_is_global_engine_enabled_async:
 * @bus: An #IBustBus.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Check if the current global engine is enabled or not asynchronously.
 */
void         ibust_bus_is_global_engine_enabled_async
                                        (IBustBus        *bus,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                        gpointer         user_data);

/**
 * ibust_bus_is_global_engine_enabled_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_is_global_engine_enabled_async().
 * @error: Return location for error or %NULL.
 * @returns: %TRUE if the current global engine is enabled.
 *
 * Finishes an operation started with ibust_bus_is_global_engine_enabled_async().
 */
gboolean     ibust_bus_is_global_engine_enabled_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_get_global_engine:
 * @bus: An #IBustBus.
 * @returns: (transfer none): The description of current global engine,
 * or %NULL if there is no global engine.
 *
 * Get the description of current global engine synchronously.
 */
IBustEngineDesc *
             ibust_bus_get_global_engine (IBustBus        *bus);

/**
 * ibust_bus_get_global_engine_async:
 * @bus: An #IBustBus.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL
 *      if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Get the description of current global engine asynchronously.
 */
void         ibust_bus_get_global_engine_async
                                        (IBustBus        *bus,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_get_global_engine_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_get_global_engine_async_finish().
 * @error: Return location for error or %NULL.
 * @returns: (transfer none): The description of current global engine,
 * or %NULL if there is no global engine.
 *
 * Finishes an operation started with ibust_bus_get_global_engine_async_finish().
 */
IBustEngineDesc *
             ibust_bus_get_global_engine_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_set_global_engine:
 * @bus: An #IBustBus.
 * @global_engine: A new engine name.
 * @returns: %TRUE if the global engine was set successfully.
 *
 * Set current global engine synchronously.
 */
gboolean     ibust_bus_set_global_engine (IBustBus        *bus,
                                         const gchar    *global_engine);

/**
 * ibust_bus_set_global_engine_async:
 * @bus: An #IBustBus.
 * @global_engine: A new engine name.
 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
 * @cancellable: A #GCancellable or %NULL.
 * @callback: A #GAsyncReadyCallback to call when the request is satisfied
 *      or %NULL if you don't care about the result of the method invocation.
 * @user_data: The data to pass to callback.
 *
 * Set current global engine asynchronously.
 */
void         ibust_bus_set_global_engine_async
                                        (IBustBus        *bus,
                                         const gchar    *global_engine,
                                         gint            timeout_msec,
                                         GCancellable   *cancellable,
                                         GAsyncReadyCallback
                                                         callback,
                                         gpointer        user_data);

/**
 * ibust_bus_set_global_engine_async_finish:
 * @bus: An #IBustBus.
 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
 *   ibust_bus_set_global_engine_async().
 * @error: Return location for error or %NULL.
 * @returns: %TRUE if no IPC errros. %FALSE otherwise.
 *
 * Finishes an operation started with ibust_bus_set_global_engine_async().
 */
gboolean     ibust_bus_set_global_engine_async_finish
                                        (IBustBus        *bus,
                                         GAsyncResult   *res,
                                         GError        **error);

/**
 * ibust_bus_set_watch_dbus_signal:
 * @bus: An #IBustBus.
 * @watch: %TRUE if you want ibustbus to emit "name-owner-changed" signal when
 * ibust-daemon emits the NameOwnerChanged DBus signal.
 *
 * Start or stop watching the NameOwnerChanged DBus signal.
 */
void         ibust_bus_set_watch_dbus_signal
                                        (IBustBus        *bus,
                                         gboolean        watch);

/**
 * ibust_bus_set_watch_ibust_signal:
 * @bus: An #IBustBus.
 * @watch: %TRUE if you want ibustbus to emit "global-engine-changed" signal when
 * ibust-daemon emits the GlobalEngineChanged IBust signal.
 *
 * Start or stop watching the GlobalEngineChanged IBust signal.
 */
void         ibust_bus_set_watch_ibust_signal
                                        (IBustBus        *bus,
                                         gboolean        watch);

/* declare config apis */
/**
 * ibust_bus_get_config:
 * @bus: An #IBustBus.
 * @returns: (transfer none): An #IBustConfig object which is configurable with
 * @bus.
 *
 * Get the config instance from #IBustBus.
 */
IBustConfig  *ibust_bus_get_config        (IBustBus        *bus);

G_END_DECLS
#endif
